home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 October / EnigmA AMIGA RUN 01 (1995)(G.R. Edizioni)(IT)[!][issue 1995-10][Aminet 7].iso / Aminet / dev / m2 / ModGen.lha / ModGen / ModGen.doc < prev    next >
Text File  |  1995-04-20  |  11KB  |  261 lines
  1. Documentation to the program
  2.  
  3.                                 ______
  4.       /|   /|                / /
  5.      / |  / |   ____   ____ / / ____  ____  ____
  6.     /  | /  |  /    / /    / /     / /___/ /   /
  7.    /   |/   | /____/ /____/ /_____/ /___  /   /    V1.0
  8.  
  9.                                           (c) 1995 by Frank Lömker
  10.  
  11. E-Mail: floemker@techfak.uni-bielefeld.de
  12.  
  13. ModGen is based directly on
  14.   - OG V37.11 by Thomas Igracki and
  15.   - GenOberon V1.0 by Kai Bolay and Jan van den Baard.
  16.  
  17. Copyright:
  18. ~~~~~~~~~
  19.  The program is Freeware. It is freely distributable and may be changed
  20.  and recompiled as long as no profit is taken out of it. Changes must be
  21.  documented.
  22.  
  23. Libraries:
  24. ~~~~~~~~~
  25.  The program needs the following external libraries:
  26.     - reqtools.library  V38    ( (c) by Nico François )
  27.     - nofrag.library  V2       ( (c) by Jan van den Baard )
  28.     - gadtoolsbox.library  V39 ( (c) by Jan van den Baard )
  29.  Should the program be able to load crunched files, the library
  30.     - powerpacker.library  V35 ( (c) by Nico François )
  31.  will be needed.
  32.  
  33. Program:
  34. ~~~~~~~
  35.  ModGen is a modula source code generator for GadToolsBox V2.0. It generates
  36.  code for the compiler Turbo Modula-2 V1.40 by Amritpal Mann.
  37.  
  38.  From Workbench you can pass 3 arguments to ModGen. The 1. argument is the
  39.  GUI-file, which should be converted. The 2. argument is the name of the
  40.  sourcecode to be generated by ModGen and the 3. argument is the name of the
  41.  sourcecode for the screen, if an extrafile should be generated for this.
  42.  
  43.  From Shell the start looks like this:
  44.    Format: ModGen [<GUIFile>] [<DestFile>] [<ScreenFile>] [OPENFONT]
  45.                   [SYSFONT] [RASTER] [UNDERMOUSE] [PORT] [ICON] [NOGUI]
  46.                   [OPT OSRUPI]
  47.    Template: NAME,TO=AS,SCREEN,OPENFONT/S,SYSFONT/S,RASTER/S,UNDERMOUSE/S,
  48.              PORT/S,ICON/S,NOGUI/S,OPT/K
  49.  
  50.    The first 3 arguments ([<GUIFile>] [<DestFile>] [<ScreenFile>]) are
  51.    identical to the Workbench arguments.
  52.  
  53.    The other arguments:
  54.  
  55.    NOGUI
  56.      ModGen opens no window. If NOGUI is not given, the other arguments
  57.      (OPENFONT - ICON  or OPT) will be ignored.
  58.    OPENFONT or OPT O
  59.      If the option "Font Adaptive" from the preferences of GadToolsBox
  60.      is not selected for the GUI-file and a diskfont is used, the code that
  61.      will open and close the used font will be generated.
  62.    SYSFONT or OPT S
  63.      If the option "Font Adaptive" from the preferences of GadToolsBox
  64.      is selected for the GUI-file the generated  source will adapt to the
  65.      system default font, if this option is selected. When this option is
  66.      off the generated source will use the screen font to adapt to.
  67.    RASTER or OPT R
  68.      The generated windows will be filled with a raster which is used by
  69.      GadToolsBox and the auto-requester of the Workbench (and also by
  70.      ModGen).
  71.    UNDERMOUSE or OPT U
  72.      The generated windows will be opened under the mouse.
  73.    PORT or OPT P
  74.      The windows will share one MessagePort. So the messages for all
  75.      windows can be received on this one port.
  76.    ICON or OPT I
  77.      If the generated files don't have an icon, they will be saved with
  78.      the icon "MODULA:Icons/txt".
  79.  
  80.  If NOGUI is not given or the program is started from Workbench, ModGen
  81.  will first load the preferences (the state of the options OPENFONT - ICON)
  82.  from the file "ENV:GadToolsBox/GenMod.prefs". Then a window is opened
  83.  where the program can be controled:
  84.  
  85.    Source, Dest, Screen
  86.      This names are equivalent to the 3 Workbench arguments. The gadgets to
  87.      the right of the string gadgets can be used to pop up a filerequester
  88.      in which you can select the files.
  89.    Preferences
  90.      This options are equivalent to the options, which can be passed from
  91.      shell.
  92.    Windows
  93.      In this listview all the windows of the GUI-file and the screen are
  94.      listed. If only a part of the code should be generated, the range can
  95.      be selected at this place.
  96.    from
  97.      If this gadget is selected, it is possible to select in the listview
  98.      the first bound of the area, which should be saved.
  99.    to
  100.      If this gadget is selected, it is possible to select in the listview
  101.      the second bound of the area, which should be saved.
  102.    All
  103.      The complete sourcecode (all windows and the screen) is generated in
  104.      the file <Dest>.
  105.    Selected
  106.      Only sourcecode for the area, which is selected by from and to, is
  107.      generated. If the screen is included in this area, the sourcecode for
  108.      this is saved under the name <Screen>. The remaining code is saved in
  109.      the file <Dest>. This code imports the part for the screen from the
  110.      file <Screen>, so that this name is needed even if the screen is not
  111.      in the selected area.
  112.    SavePref
  113.      The preferences are saved in the files "ENV:GadToolsBox/GenMod.prefs"
  114.      and "ENVARC:GadToolsBox/GenMod.prefs"
  115.    About
  116.      This shows some information about ModGen.
  117.    Quit and Closegadget
  118.      The program quits.
  119.  
  120. The generated sourcecode:
  121. ~~~~~~~~~~~~~~~~~~~~~~~~
  122.  If the GETFILE-gadget is used, the generated code imports the module
  123.  GetFile. Furthermore, you must link with the object code "InitGetC.o",
  124.  which containes the dispatcher for the BOOPSI-image.
  125.  
  126.  From here on mean:
  127.    <Project-Name> Name entered in the Edit Data requester from the
  128.                   Window menu
  129.    <Gadget-Label> Name entered in a Label gadget of one of the gadget kind
  130.                   requester
  131.    <Menu-Label>   Name entered in the Label gadget of the Menu Editor
  132.  
  133.  Following exported routines are generated:
  134.  
  135.  PROCEDURE SetupScreen (): INTEGER , with a Customscreen and the Workbench
  136.  PROCEDURE SetupScreen (pub:y.ADDRESS): INTEGER   with a Publicscreen
  137.    This routine will open or lock the screen and get it's visual info. When
  138.    requested this routine will also open the font. Also it will test the
  139.    setup of the boopsi image for the GETFILE gadget when such a gadget is
  140.    used.
  141.    This procedure is in the file <Screen> if Selected is used to generate
  142.    the code.
  143.    The RETURN codes:
  144.       0  No error.
  145.       1  Could not open or lock the screen.
  146.       2  Could not get the screen it's visual info.
  147.       3  Could not open the font.
  148.       4  Could not set-up the GETFILE boopsi class.
  149.  
  150.  PROCEDURE CloseDownScreen;
  151.    This routine will free the resources taken by SetupScreen. This routine
  152.    must even be called if SetupScreen returned an error.
  153.    This procedure is in the file <Screen> if Selected is used to
  154.    generate the code.
  155.  
  156.  PROCEDURE Create<Project-Name>Gadgets (): INTEGER;
  157.    There are as much of these routines as there are Project Windows with
  158.    gadgets in the generated file. These routines will set-up the gadgets.
  159.    The RETURN codes:
  160.       0  No error.
  161.       1  Could not create a gadget context.
  162.       2  Error during the gadget creation.
  163.       7  Could not get a GETFILE boopsi object.
  164.       8  CloneTagItems was not possible.
  165.  
  166.  PROCEDURE Open<Project-Name>Window (createGads: BOOLAN): INTEGER;
  167.                          if the window has gadgets
  168.  PROCEDURE Open<Project-Name>Window (): INTEGER;
  169.                          if the window has no gadgets
  170.    There are as much of these routines as there are Project Windows in the
  171.    generated file. These routines will set-up the gadgets (if present and
  172.    asked for) and menus and open the window.
  173.    The RETURN codes:
  174.       0  No error.
  175.       1  Could not create a gadget context.
  176.       2  Error during the gadget creation.
  177.       3  Could not create the menus.
  178.       4  LayoutMenus not possible.
  179.       5  Could not open the system font (option SYSFONT).
  180.       6  SetMenuStrip not possible.
  181.       7  Could not get a GETFILE boopsi object.
  182.       8  CloneTagItems was not possible.
  183.      20  Could not open the window.
  184.  
  185.  PROCEDURE Close<Project-Name>Window;
  186.    There are as much of these routines as there are Project Windows in the
  187.    generated file. These routines will free all resources that the
  188.    Open<Project_Name>Window routine has taken. This routine must even be
  189.    called if Open<Project_Name>Window returned an error.
  190.  
  191.  PROCEDURE <Project-Name>Render;
  192.    Each Project Window which has texts or BevelBoxes attached to it or for
  193.    which the option RASTER was on, will have a routine which renders these
  194.    texts and BevelBoxes and generated the background in the window. This
  195.    routine must also be called by the user program upon receiving a
  196.    REFRESHWINDOW message at the window port. When such a message is
  197.    received this routine must be called between the GT_BeginRefresh and
  198.    GT_EndRefresh calls. An example:
  199.      IF REFRESHWINDOW <= Class THEN
  200.        GT_BeginRefresh (<Project-Name>Wnd);
  201.        <Project-Name>Render;
  202.        GT_EndRefresh (<Project-Name>Wnd,TRUE);
  203.      END;
  204.  
  205.  The generated file also contains the following global variables and
  206.  constants:
  207.  
  208.    The variables Scr, VisualInfo, Font, Attr and Topaz80 are in the file
  209.    <Screen> if Selected is used to generate the code.
  210.  
  211.    Scr: I.ScreenPtr;           Pointer to the opened or locked screen
  212.    VisualInfo: y.ADDRESS;      Pointer to the visual info of the screen
  213.  
  214.  The following variables are only generated when the file contains gadgets
  215.  or menus and when the OpenFont routine is generated and when the window
  216.  has a zoom gadget:
  217.  
  218.    <Project-Name>GList: I.GadgetPtr;            The created gadgets
  219.    <Project-Name>Menus: I.MenuPtr;              The created menus
  220.    <Project-Name>Zoom: ARRAY [0..3] OF INTEGER; 2. window position
  221.    Topaz80: g.TextAttr;
  222.    Attr: g.TextAttr;                            The opened font
  223.    Font: g.TextAttrPtr;                         Pointer to the opened font
  224.  
  225.  Also generated are pointers for each project window:
  226.  
  227.    <Project-Name>Wnd: I.WindowPtr;
  228.  
  229.  The following variables contain the window position:
  230.  
  231.    <Project-Name>Left     left edge
  232.    <Project-Name>Top      top edge
  233.    <Project-Name>Width    width
  234.    <Project-Name>Height   height
  235.  
  236.    This variables are initialized in the main part of the generated modul.
  237.  
  238.  Also the generated file contains the gadget array's for each project
  239.  window which are defined as following:
  240.  
  241.    <Project-Name>Gadgets: ARRAY [0..<Project-Name>CNT-1] OF I.GadgetPtr;
  242.  
  243.    The constant <Project-Name>CNT contains the number of gadgets in the
  244.    window.
  245.  
  246.  To access the pointers in this array the program generates constants which
  247.  specify the position of a certain gadget in the array:
  248.  
  249.    GD<Gadget-Label>
  250.  
  251.  The underlined charcters of all gadgets are given in the string
  252.  <Project-Name>HotKeys.
  253.  
  254. Compiling ModGen:
  255. ~~~~~~~~~~~~~~~~
  256.  To compile ModGen type:
  257.  
  258.    m2b ModGen gtxs.lib nofrags.lib rqtoolss.lib InitGetC.o
  259.  
  260.  Frank
  261.